Getting Status Changes Notifications Using Webhooks

Webhooks allow you to get programmatical notifications from FintechOS about status changes of your envelope as they happen.

For every envelope event, webhooks will send the notifications as an HTTP POST request, with a JSON body, to the endpoint you specify. They will push information to your endpoint.

Using FintechOS webshooks you can receive notification for the following events:

  • the client opened the document
  • the signature for client is finished
  • the whole document is signed

To Get Envelope Status Changes Notifications Using Webhooks

Step 1. Configure webhooks

Prerequisite: You need to know the webhook ID received from FintechOS.

To get notifications on envelope status changes using webhooks, in the sign request, add the webhook finish URL (WebhookUrl ) and webhook for status URL(WebhookStatusUrl).

In this example, we set notifications for all events that occur on the document 'signedContract'.

Copy 
{
        "Authentication": {
           "Username": "john.doe@fintechos.com",
           "Key": "72b2f349-b5c7-4df7-478d-efd8a7f4a6c9"
        },
        "SignedDocumentName": "signedContract",
         
        "WebhookUrl":"{FTOSHook}/hookId_receivedFromFTOS?test=12345&asdf=abc&envelopeId=##EnvelopeId##&recipientEmail=##RecipientEmail##&recipientOrder=##RecipientOrder##&action=##Action##",
        "WebhookStatusUrl":"{FTOSHook}/hookId_receivedFromFTOS?test=12345&asdf=abc&envelopeId=##EnvelopeId##&recipientEmail=##RecipientEmail##&recipientOrder=##RecipientOrder##&action=##Action##",
         
        "WorkstepConfigs": [
           {
           ...
           }
        ]
}

Where:

  • {FTOSHook} is the webhook ID received from FintechOS. It is a constant value for all the requests from your app. In the query parameters of the WebHookUrl (after the ? mark) you can add custom values, for example test=12345 and you will receive the same value on the notification.
  • WebhookUrl will be called only when the envelope is finished (all worksteps have been completed) and you can download the signed document.
  • WebhookStatusUrl will be called for every status change of the envelope.

Step 2. Create an endpoint for the webhook

Create the endpoint (action) that contains the logic for receiving the webhook. In most of the cases, in the server automation scripts, call the request downloadSignedDocument and get the intermediate URL for the second workstep or download the signed document (the pdf file).

The example request provided at Step 1 returns the following data in the server automation script:

Copy 
{
    "UserId": "4afdc8a9-eb91-4359-81d6-c3a462fae866",
    "Ids": null,
    "Id": "00000000-0000-0000-0000-000000000000",
    "EntityName": null,
    "PreviousBusinessStatus": null,
    "PreviousBWS": null,
    "BusinessStatus": null,
    "CurrentBWS": null,
    "Values": null,
    "AdditionalValues": null,
    "PropertyBag": {},
    "ExecutionDepth": 0,
    "MessageSuccess": false,
    "Message": null,
    "ReloadPage": false,
    "NavigateToUrl": null,
    "NavigateToEntityPage": false,
    "NavigateToEntityPageOnEdit": false,
    "NavigateToEntityName": null,
    "NavigateToEntityFormName": null,
    "NavigateToEntityId": null,
    "NavigateToEntityInsertDefaults": null,
    "Data": {
        "test": "12345",
        "asdf": "abc",
        "envelopeId": "7bfa100a-f52c-4915-b25d-210e6bb82f48",
        "recipientEmail": "",
        "recipientOrder": "",
        "action": "workstepOpened"
    },
    "Fetch": null,
    "BeforeValues": null,
    "MergedValues": {}
}
Copy 
{
    "UserId": "4afdc8a9-eb91-4359-81d6-c3a462fae866",
    "Ids": null,
    "Id": "00000000-0000-0000-0000-000000000000",
    "EntityName": null,
    "PreviousBusinessStatus": null,
    "PreviousBWS": null,
    "BusinessStatus": null,
    "CurrentBWS": null,
    "Values": null,
    "AdditionalValues": null,
    "PropertyBag": {},
    "ExecutionDepth": 0,
    "MessageSuccess": false,
    "Message": null,
    "ReloadPage": false,
    "NavigateToUrl": null,
    "NavigateToEntityPage": false,
    "NavigateToEntityPageOnEdit": false,
    "NavigateToEntityName": null,
    "NavigateToEntityFormName": null,
    "NavigateToEntityId": null,
    "NavigateToEntityInsertDefaults": null,
    "Data": {
        "test": "12345",
        "asdf": "abc",
        "envelopeId": "7bfa100a-f52c-4915-b25d-210e6bb82f48",
        "recipientEmail": "",
        "recipientOrder": "",
        "action": "envelopeFinished",
        "FTOSIsFinishCallback": "1"
    },
    "Fetch": null,
    "BeforeValues": null,
    "MergedValues": {}
}